home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Demos / Evatac Software / Preditor 3.0 / Documentation / Writing Language Modules < prev   
Text File  |  1996-02-18  |  7KB  |  100 lines
  1.  
  2.            Language Module Builder
  3.  
  4. This file describes how to use the libraries and tools in this folder to build your own language module for the Preditor text editor, either for an existing language (but with improved/modified parsing) or for a new language that is not included with the Preditor release.  Source code for all of the language modules shipped with Preditor is included.  This document gives an overview of writing a language module.  Refer to the documentation if you need a more detailed description.
  5.  
  6. There are 2 major steps in creating a language module.
  7.  
  8.   1.  Constructing and editing the language module using
  9.        the "Language Module Editor" application.
  10.   2.  Writing and compiling the language source.
  11.   
  12.  
  13. Using the Language Module Editor application
  14.  
  15. The Language Module Editor edits various characteristics of a language.   To edit a language, open the language module using the Language Module Editor application.  To create a new language module, it's easiest to duplicate an existing language module, and then rename it.  Future versions of the editor will allow you to create a new language module from within the editor.  The editor allows you to modify the following characteristic of the language module:
  16.  
  17.         • Brackets                Bracket set (i.e. [ ], { }, begin end)
  18.         • Electrics                Characters the are electric
  19.         • Extensions        File extensions (i.e.  .c, .pas...)
  20.         • Keywords            Keywords and custom keywords
  21.         • Styles                         Styles for various tokens in the language.
  22.         • Templates            Template definitions
  23.  
  24. You will also want to create your own small icon suite for the language.  To do this, you need to edit the language module with ResEdit, and edit the icon suite with ID = 600.  Preditor uses this small icon when displaying the language type in the info bar, and also in summary  window.  You may also want to set the version information by editing the 'vers' resources.
  25.  
  26.  
  27. Brackets
  28.  
  29. Each bracket set entry is a string, with the left and right bracket being separated by a space " ".  The left and right brackets can be any arbitrary character sequence.  For example, the Pascal bracket set is:
  30.  
  31.         Number of Brackets        6
  32.  
  33.         1)        "( )"
  34.         2)        "[ ]"
  35.         3)        "{ }"
  36.         4)        "begin end"
  37.         5)        "case end"
  38.         6)        "while end"
  39.  
  40. Preditor uses the bracket definition when hiliting between brackets.  For example, in Pascal, double clicking on the word "begin" will hilite all text between begin and the corresponding end.
  41.  
  42.  
  43. Electrics
  44.  
  45. The Electrics panel lets you set a string that contains all characters that are electric. Characters that are electric need to be handled as such in the language source (C code).  Electric characters are characters that when typed, automatically do some formatting.  For example, a common electric character is ';'.  When typing a ';', the semi-colon is entered followed by a new line and indentation.  The behavior of the electric character is defined by C code in the language module.  Refer to the CParse.c file for an example of how to program the electric character behavior.
  46.  
  47.  
  48. Extensions
  49.  
  50. The Extensions panel lets you edit, add and remove file extensions for a language.  An extension is a suffix string that gives possible file name suffixes for the language (i.e.  ".c", ".h", etc.).  Preditor uses these extensions to determine what language the file is when opening the file.
  51.  
  52.  
  53. Keywords
  54.  
  55. The Keywords panel lets you customize the set of keywords and the set of custom keywords for the language.  The keywords sets are used by the parser, to help tokenize the source, and to format the keywords when displaying the source.
  56.  
  57.  
  58. Styles
  59.  
  60. You can define as few or as many different code types as you wish.  Typically, you define types for functions, keywords and comments.  For each code type you want to define, it needs to have a style and style name defined for it.  The code types your parsing code returns, should correspond to the style's index in the list of styles (i.e. the first style is code type = 0).  These code types typically have symbolic named, defined in the header file for the parse code.  For example:
  61.  
  62. enum {
  63.     kFunction        = 0,
  64.     kKeyword,
  65.     kComment,
  66.     kCustomKeyword,
  67.        kDisabled
  68. };
  69.  
  70. The Styles panel lets you add, remove and edit the set of styles.  The order of the styles in the list of styles needs to correspond to the code-types, defined above (for example).
  71.  
  72.  
  73. Templates
  74.  
  75. The Templates panel lets you add, remove and edit template for the language.  A template consists of a key, and template text.  The key is replaced with the template (similar to how a glossary entry behaves) when "tab" is hit after the key (and there is no other text on that line), or when Insert Template is selected from the Special menu within Preditor.
  76.  
  77. The template text is somewhat special.  It allows you to specify temporary markers, indenting and back-tabbing when the template is inserted.  The special characters are:
  78.  
  79.                 •        (Option-8) Set a temporary marker
  80.                 Δ        (Option-J) Backtab
  81.                 \r    Carriage return
  82.                 \t    Tab
  83.  
  84. For example, the template for "while" in the C language module is:
  85.  
  86.         while    --->        while (•) {\r\t•\r}//endwhile•
  87.  
  88. The template is inserted and indented based on the position of the keyword.  That is, in this example -- the "} //endwhile" text be indented to line up with the "while" text.
  89.  
  90. So when editing in Preditor, and you type "while" and then <tab>, the template will automatically insert itself, and the cursor will be moved to the first set marker (in the case between the "()").  You can use the Next Marker and Previous Marker commands to jump forward and backward through all of the markers set by the template.
  91.  
  92.  
  93. Editing and compiling the language module source
  94.  
  95. The most important part of creating a language module is the language module source.  The source is what does the parsing of the language, indenting for the language, and also handles inserting text for the electric characters.  The source code and project file have been included for all of the languages shipped with Preditor.  They are located in the "Source" folder.  These are Code Warrior project files for compiling both the 68K and PPC versions of the parse code.  The project files insert the compiled code directly into the language module.  For any changes to take place, you need to copy the new language module back into the "Languages" folder in the "Preditor Folder". 
  96.  
  97.  
  98. We hope that third-parties will write improved language modules for the language modules that already exist, and new language modules for those that do not exist.  If you'd like to have a language module included with the Preditor 3.0 distribution, please send mail to info@evatac.com.  If you have questions about writing language modules, please send mail to suport@evatac.com.
  99.  
  100.